/**
   \file  action.hh
   \brief Abstract base class defining the interface for different
   actions supported by the libgist driver program.

   This file defines an ABC that specifies a common interface for the
   different actions the libgist algorithms can perform. The libgist
   driver program's main function uses an object factory to create an
   action object using the second command line argument, passing it to
   the algorithm object named by the third command line argument. For
   example, let's say the user wants to train some algorithm "foo" and
   enters the command:

           gist dataset_name train foo

   The gist driver program will create a foo_driver object by passing the
   argument "foo" to an object factory that churns out objects derived
   from the algorithm_tester class. It will then create a train object
   using a factory that gets the second argument and "attach" the action
   to the algorithm. Finally, it will use these interface objects to
   test-drive the user-specified algorithm, i.e., perform the requested
   action on the requested algorithm.
*/

/*
   This file is part of libgist.

   libgist is free software; you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by the
   Free Software Foundation; either version 2 of the License, or (at your
   option) any later version.

   libgist is distributed in the hope that it will be useful, but WITHOUT
   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
   for more details.

   You should have received a copy of the GNU General Public License
   along with libgist; if not, write to the Free Software Foundation,
   Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
*/

/*
   REVISION HISTORY

   $HeadURL: http://libgist.googlecode.com/svn/branches/siagian_dev/drv/action.hh $
   $Id: action.hh 53 2011-09-01 08:09:28Z libgist@gmail.com $
*/

#ifndef GISTDRV_ACTION_BASE_DOT_HH
#define GISTDRV_ACTION_BASE_DOT_HH

//------------------------------ HEADERS --------------------------------

// gistdrv
#include "algorithm_tester.hh"

//----------------------- NAMESPACE DEFINITION --------------------------

namespace gistdrv {

//------------------------- CLASS DEFINITION ----------------------------

/**
   \brief Abstract base class defining common interface for different
   actions supported by the libgist algorithms.

   libgist provides canned implementations of several different gist
   algorithms but does not attempt to unify the different commands,
   arguments, steps, etc. into a common high-level framework. That task
   falls to the library's clients. This "low-level" approach simplifies
   the implementation of libgist. Additionally, if a client needs only
   one of the algorithms provided by libgist, then it does not have to
   bother with creating an elaborate higher-level interface nor does it
   have to structure its code to conform to whatever high-level interface
   libgist's designers would have come up with.

   However, in some situations (e.g., a driver program for testing all
   the libgist algorithms:), a common interface to the different
   algorithms helps keep the client program's design sane. This class
   (and its subclasses) in conjunction with algorithm_tester and
   subclasses represents one possible way to implement such a common
   interface to libgist.

   The idea here is to encapsulate the details of different actions in a
   common interface. Despite the fact that each libgist algorithm
   supports a different set of methods to accomplish its particular way
   of achieving scene categorization, there is some high-level
   commonality. For instance, in general, all the libgist algorithms work
   in one of two basic modes, viz., training and testing.

   Furthermore, regardless of the specifics of a particular algorithm,
   these actions involve pretty much the same steps. For example, to
   train any algorithm, we have to first retrieve, from the config file,
   the list of training images organized into their respective categories
   and then load these images one-by-one, passing them to the algorithm.

   The exact API used to effect these actions will differ for different
   algorithms. However, those details are taken care of by the algorithm
   driver objects (which are accessed via the common interface provided
   by algorithm_tester).
*/
class action {
protected:
   /// An action has to be tied to an algorithm. This data member holds a
   /// reference to the algorithm driver object requested by the user.
   /// \return
   algorithm_tester* m_algo ;

   /**
      \brief Initialize action and link it to the provided algorithm.
      \param algo Algorithm interface object.

      This constructor initializes the action and links it to the
      supplied algorithm interface object. Thus, when the action is
      executed, it will be performed on the algorithm object passed in
      during initialization.

      Note that this a protected constructor because action objects are
      created by a factory and cannot be instantiated directly by
      clients.
   */
   action(algorithm_tester*) ;

public:
   /**
      \brief Execute the action.

      Once an action has been setup, we can execute it by invoking this
      method. All derived classes are expected to implement this method,
      providing the necessary steps to fulfill the requested action. They
      should use the m_algo data member to perform the action on the
      user-specified algorithm.
   */
   virtual void exec() = 0 ;

   /// Clean-up.
   virtual ~action() ;
} ;

//-----------------------------------------------------------------------

} // end of namespace encapsulating this file's definitions

#endif

/* So things look consistent in everyone's emacs... */
/* Local Variables: */
/* indent-tabs-mode: nil */
/* End: */

